<html>
<head></head>
<body><a name="ZH-CN_TOPIC_0000002313994852"></a><a name="ZH-CN_TOPIC_0000002313994852"></a>
<h1>弹出框控制器</h1>
<div><p>
    ArkUI的弹出框控制器在绑定弹出框后，可提供对弹出框的操作能力，当前支持关闭功能。可以将控制器传入弹出框内容区域后进行操作。</p>
    <p>从API version 18开始，可设置<a
            href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-promptaction#dialogcontroller18"
            target="_blank">controller</a>参数以绑定控制器，通过控制器能够操作弹出框。</p>
    <div class="section" id="使用约束"><a name="ZH-CN_TOPIC_0000002313994852__%E4%BD%BF%E7%94%A8%E7%BA%A6%E6%9D%9F"></a><a
            name="%E4%BD%BF%E7%94%A8%E7%BA%A6%E6%9D%9F"></a>     <h4>使用约束</h4>
        <p>目前<a
                href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#opencustomdialogwithcontroller18"
                target="_blank">openCustomDialogWithController</a>和<a
                href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#presentcustomdialog18"
                target="_blank">presentCustomDialog</a>支持通过controller参数来绑定弹出框进行操作，目前<a
                href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-custom-component-api#getdialogcontroller18"
                target="_blank">getDialogController</a>支持获取自定义组件所在的弹出框的控制器。</p>
        <div class="note"><img originheight="38" originwidth="102"
                               src="https://communityfile-drcn.op.dbankcloud.cn/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20250709163043.31195296940764835073514730888684:50001231000000:2800:311E49936E06A1CE5B1C1F6B0DF3868AED161B348F77FE95B1B31C1615B475B1.png"><span
                class="notetitle"> </span>
            <div class="notebody"><p>一个弹出框控制器只能绑定一个弹出框，且操作只对该弹出框生效。</p>
                <p>使用<a
                        href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-custom-component-api#getdialogcontroller18"
                        target="_blank">getDialogController</a>获取弹出框控制器时，如果当前自定义组件不在弹出框中显示则获取为undefined。
                </p></div>
        </div>
    </div>
    <div class="section" id="创建自定义内容为componentcontent的弹出框控制器"><a
            name="ZH-CN_TOPIC_0000002313994852__%E5%88%9B%E5%BB%BA%E8%87%AA%E5%AE%9A%E4%B9%89%E5%86%85%E5%AE%B9%E4%B8%BAcomponentcontent%E7%9A%84%E5%BC%B9%E5%87%BA%E6%A1%86%E6%8E%A7%E5%88%B6%E5%99%A8"></a><a
            name="%E5%88%9B%E5%BB%BA%E8%87%AA%E5%AE%9A%E4%B9%89%E5%86%85%E5%AE%B9%E4%B8%BAcomponentcontent%E7%9A%84%E5%BC%B9%E5%87%BA%E6%A1%86%E6%8E%A7%E5%88%B6%E5%99%A8"></a>
        <h4>创建自定义内容为ComponentContent的弹出框控制器</h4>
        <div class="note"><img originheight="38" originwidth="102"
                               src="https://communityfile-drcn.op.dbankcloud.cn/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20250709163043.28899645381294480414249539783620:50001231000000:2800:AF3FF9A96A3922417AB0A343A69572D6780CB8A4D1F5AC086D52437058F8472E.png"><span
                class="notetitle"> </span>
            <div class="notebody"><p>详细变量定义请参考<a href="#完整示例">完整示例</a>。</p></div>
        </div>
        <ol>
            <li>初始化一个自定义弹出框内容区的入参类，内部包含弹出框控制器。</li>
        </ol>
        <pre class="ts">class Params {
  public text: string = ''
  public dialogController: promptAction.CommonController = new promptAction.DialogController()
  constructor(text: string, dialogController: promptAction.CommonController) {
    this.text = text
    this.dialogController = dialogController
  }
}</pre>
        <ol>
            <li>初始化一个自定义的弹出框内容区，内部包含一个按钮，该按钮通过该自定义组件自带的弹出框控制器实现关闭功能。
            </li>
        </ol>
        <pre class="ts">@Component
struct MyComponent {
  build() {
    Column({ space: 5 }) {
      Button('点我关闭弹窗：通过自定义组件自带的DialogController')
        .onClick(() =&gt; {
          let dialogController: promptAction.DialogController = this.getDialogController()
          if (dialogController !== undefined) {
            dialogController.close()
          }
        })
    }
  }
}</pre>
        <ol>
            <li>
                初始化另一自定义弹出框内容区，其中包含一个Text组件和一个按钮，该按钮通过外部传递的弹出框控制器用于关闭弹出框，并且该内容区还包含前一个自定义弹出框内容区。
            </li>
        </ol>
        <pre class="ts">@Builder
function buildText(params: Params) {
  Column({ space: 5 }) {
    Text(params.text)
      .fontSize(30)
    if (params.dialogController !== undefined) {
      Button('点我关闭弹窗：通过外部传递的DialogController')
        .onClick(() =&gt; {
          params.dialogController.close()
        })
    }
    MyComponent()
  }
  .width(300)
  .height(200)
  .backgroundColor('#FFF0F0F0')
}</pre>
        <ol>
            <li>初始化一个弹出框控制器，并通过设置控制器参数来初始化一个弹出框内容实体对象。最后，通过调用<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#uicontext"
                    target="_blank">UIContext</a>中的<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#getpromptaction"
                    target="_blank">getPromptAction</a>方法获取<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#promptaction"
                    target="_blank">PromptAction</a>对象，再通过该对象调用<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#opencustomdialogwithcontroller18"
                    target="_blank">openCustomDialogWithController</a>接口，并且设置初始化的内容实体对象和控制器参数以创建弹出框。
            </li>
        </ol>
        <pre class="ts">let dialogController: promptAction.CommonController = new promptAction.DialogController()
let contentNode: ComponentContent&lt;Object&gt; =
  new ComponentContent(this.getUIContext(), wrapBuilder(buildText), new Params(this.message, dialogController))
this.getUIContext().getPromptAction().openCustomDialogWithController(
  contentNode, dialogController, this.baseDialogOptions).catch((err: BusinessError) =&gt; {
  console.error('openCustomDialogWithController error: ' + err.code + ' ' + err.message)
})</pre>
    </div>
    <div class="section" id="创建自定义内容为custombuilder的弹出框控制器"><a
            name="ZH-CN_TOPIC_0000002313994852__%E5%88%9B%E5%BB%BA%E8%87%AA%E5%AE%9A%E4%B9%89%E5%86%85%E5%AE%B9%E4%B8%BAcustombuilder%E7%9A%84%E5%BC%B9%E5%87%BA%E6%A1%86%E6%8E%A7%E5%88%B6%E5%99%A8"></a><a
            name="%E5%88%9B%E5%BB%BA%E8%87%AA%E5%AE%9A%E4%B9%89%E5%86%85%E5%AE%B9%E4%B8%BAcustombuilder%E7%9A%84%E5%BC%B9%E5%87%BA%E6%A1%86%E6%8E%A7%E5%88%B6%E5%99%A8"></a>
        <h4>创建自定义内容为CustomBuilder的弹出框控制器</h4>
        <div class="note"><img originheight="38" originwidth="102"
                               src="https://communityfile-drcn.op.dbankcloud.cn/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20250709163043.88592021128067885004517125974276:50001231000000:2800:E99139BDBF3D924999655FC27EB915B7718CFD1C72B317ACC710B8AEAA47CC1A.png"><span
                class="notetitle"> </span>
            <div class="notebody"><p>详细变量定义请参考<a href="#完整示例">完整示例</a>。</p></div>
        </div>
        <ol>
            <li>
                初始化一个自定义弹出框内容区，内部包含一个Text组件和一个按钮，该按钮通过外部传递的弹出框控制器实现关闭功能。
            </li>
        </ol>
        <pre class="ts">@Builder customDialogComponent(dialogController: promptAction.DialogController) {
  Column({ space: 5 }) {
    Text(this.message)
      .fontSize(30)
    if (dialogController !== undefined) {
      Button('点击关闭弹窗：通过外部传递的DialogController')
        .onClick(() =&gt; {
          dialogController.close()
        })
    }
  }
  .height(200)
  .padding(5)
  .justifyContent(FlexAlign.SpaceBetween)
  .backgroundColor('#FFF0F0F0')
}</pre>
        <ol>
            <li>初始化一个弹出框控制器，并通过调用<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#uicontext"
                    target="_blank">UIContext</a>中的<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#getpromptaction"
                    target="_blank">getPromptAction</a>方法获取<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#promptaction"
                    target="_blank">PromptAction</a>对象，再通过该对象调用<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#presentcustomdialog18"
                    target="_blank">presentCustomDialog</a>接口，设置初始化的内容实体对象和控制器参数以创建弹出框。
            </li>
        </ol>
        <pre class="ts">let dialogController: promptAction.CommonController = new promptAction.DialogController()
this.getUIContext().getPromptAction().presentCustomDialog(() =&gt; {
  this.customDialogComponent(dialogController)
}, dialogController, this.dialogOptions).catch((err: BusinessError) =&gt; {
  console.error('presentCustomDialog error: ' + err.code + ' ' + err.message)
})</pre>
    </div>
    <div class="section" id="创建自定义内容为custombuilderwithid的弹出框控制器"><a
            name="ZH-CN_TOPIC_0000002313994852__%E5%88%9B%E5%BB%BA%E8%87%AA%E5%AE%9A%E4%B9%89%E5%86%85%E5%AE%B9%E4%B8%BAcustombuilderwithid%E7%9A%84%E5%BC%B9%E5%87%BA%E6%A1%86%E6%8E%A7%E5%88%B6%E5%99%A8"></a><a
            name="%E5%88%9B%E5%BB%BA%E8%87%AA%E5%AE%9A%E4%B9%89%E5%86%85%E5%AE%B9%E4%B8%BAcustombuilderwithid%E7%9A%84%E5%BC%B9%E5%87%BA%E6%A1%86%E6%8E%A7%E5%88%B6%E5%99%A8"></a>
        <h4>创建自定义内容为CustomBuilderWithId的弹出框控制器</h4>
        <div class="note"><img originheight="38" originwidth="102"
                               src="https://communityfile-drcn.op.dbankcloud.cn/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20250709163043.41473300390447327981713272646305:50001231000000:2800:443D1694630BFEDD58606273B707A012D039A2A03FD191F7DFB3EF6FD09E31F6.png"><span
                class="notetitle"> </span>
            <div class="notebody"><p>详细变量定义请参考<a href="#完整示例">完整示例</a>。</p></div>
        </div>
        <ol>
            <li>
                初始化一个弹出框内容区，内部包含一个Text组件、一个通过外部传递的弹出框ID用于关闭弹出框的按钮和一个通过外部传递的弹出框控制器用于关闭弹出框的按钮。
            </li>
        </ol>
        <pre class="ts">@Builder customDialogComponentWithId(dialogId: number, dialogController: promptAction.DialogController) {
  Column({ space: 5 }) {
    Text(this.message)
      .fontSize(30)
    if (dialogId !== undefined) {
      Button('点击关闭弹窗：通过DialogID')
        .onClick(() =&gt; {
          this.getUIContext().getPromptAction().closeCustomDialog(dialogId)
        })
    }
    if (dialogController !== undefined) {
      Button('点击关闭弹窗：通过外部传递的DialogController')
        .onClick(() =&gt; {
          dialogController.close()
        })
    }
  }
}</pre>
        <ol>
            <li>初始化一个弹出框控制器，并通过调用<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#uicontext"
                    target="_blank">UIContext</a>中的<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#getpromptaction"
                    target="_blank">getPromptAction</a>方法获取<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#promptaction"
                    target="_blank">PromptAction</a>对象，再通过该对象调用<a
                    href="https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uicontext#presentcustomdialog18"
                    target="_blank">presentCustomDialog</a>接口，设置初始化的内容实体对象和控制器参数以创建弹出框。
            </li>
        </ol>
        <pre class="ts">let dialogController: promptAction.CommonController = new promptAction.DialogController()
this.getUIContext().getPromptAction().presentCustomDialog((dialogId: number) =&gt; {
  this.customDialogComponentWithId(dialogId, dialogController)
}, dialogController, this.dialogOptions).catch((err: BusinessError) =&gt; {
  console.error('presentCustomDialog error: ' + err.code + ' ' + err.message)
})</pre>
    </div>
    <div class="section" id="在customdialogcontroller内容区直接获取弹出框控制器"><a
            name="ZH-CN_TOPIC_0000002313994852__%E5%9C%A8customdialogcontroller%E5%86%85%E5%AE%B9%E5%8C%BA%E7%9B%B4%E6%8E%A5%E8%8E%B7%E5%8F%96%E5%BC%B9%E5%87%BA%E6%A1%86%E6%8E%A7%E5%88%B6%E5%99%A8"></a><a
            name="%E5%9C%A8customdialogcontroller%E5%86%85%E5%AE%B9%E5%8C%BA%E7%9B%B4%E6%8E%A5%E8%8E%B7%E5%8F%96%E5%BC%B9%E5%87%BA%E6%A1%86%E6%8E%A7%E5%88%B6%E5%99%A8"></a>
        <h4>在CustomDialogController内容区直接获取弹出框控制器</h4>
        <div class="note"><img originheight="38" originwidth="102"
                               src="https://communityfile-drcn.op.dbankcloud.cn/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20250709163043.66419999281793173693901720912097:50001231000000:2800:FD98757DA5C1AD347719B16B24E2E5AC567E10F24FA7BA513F4825E5E85CF236.png"><span
                class="notetitle"> </span>
            <div class="notebody"><p>详细变量定义请参考<a href="#完整示例">完整示例</a>。</p></div>
        </div>
        <ol>
            <li>初始化一个自定义弹出框内容区，内部包含一个Text组件和一个按钮，该按钮通过弹出框控制器关闭弹出框。</li>
        </ol>
        <pre class="ts">@CustomDialog
@Component
struct CustomDialogExample {
  controller?: CustomDialogController

  build() {
    Column({ space: 5 }) {
      Text('我是内容')
        .fontSize(30)
      Button('点我关闭弹窗：通过自定义组件自带的DialogController')
        .onClick(() =&gt; {
          let dialogController: PromptActionDialogController = this.getDialogController()
          if (dialogController !== undefined) {
            dialogController.close()
          }
        })
    }
    .height(200)
    .backgroundColor('#FFF0F0F0')
  }
}</pre>
        <ol>
            <li>初始化一个自定义弹出框构造器，关联自定义弹出框内容区。</li>
        </ol>
        <pre class="ts">let customDialogController: CustomDialogController = new CustomDialogController({
  builder: CustomDialogExample(),
})
customDialogController.open()</pre>
    </div>
    <div class="section" id="完整示例"><a name="ZH-CN_TOPIC_0000002313994852__%E5%AE%8C%E6%95%B4%E7%A4%BA%E4%BE%8B"></a><a
            name="%E5%AE%8C%E6%95%B4%E7%A4%BA%E4%BE%8B"></a>     <h4>完整示例</h4>
        <p>通过外部传递的弹出框控制器和自定义组件自带的弹出框控制器，在自定义弹出框内容区域内实现关闭功能。</p>
        <pre class="ts">import { ComponentContent, promptAction } from '@kit.ArkUI'
import { BusinessError } from '@kit.BasicServicesKit'

class Params {
  public text: string = ''
  public dialogController: promptAction.CommonController = new promptAction.DialogController()
  constructor(text: string, dialogController: promptAction.CommonController) {
    this.text = text
    this.dialogController = dialogController
  }
}

@Component
struct MyComponent {
  build() {
    Column({ space: 5 }) {
      Button('点我关闭弹窗：通过自定义组件自带的DialogController')
        .onClick(() =&gt; {
          let dialogController: promptAction.DialogController = this.getDialogController()
          if (dialogController !== undefined) {
            dialogController.close()
          }
        })
    }
  }
}

@Builder
function buildText(params: Params) {
  Column({ space: 5 }) {
    Text(params.text)
      .fontSize(30)
    if (params.dialogController !== undefined) {
      Button('点我关闭弹窗：通过外部传递的DialogController')
        .onClick(() =&gt; {
          params.dialogController.close()
        })
    }
    MyComponent()
  }
  .width(300)
  .height(200)
  .backgroundColor('#FFF0F0F0')
}

@CustomDialog
@Component
struct CustomDialogExample {
  controller?: CustomDialogController

  build() {
    Column({ space: 5 }) {
      Text('我是内容')
        .fontSize(30)
      Button('点我关闭弹窗：通过自定义组件自带的DialogController')
        .onClick(() =&gt; {
          let dialogController: PromptActionDialogController = this.getDialogController()
          if (dialogController !== undefined) {
            dialogController.close()
          }
        })
    }
    .height(200)
    .backgroundColor('#FFF0F0F0')
  }
}

@Entry
@Component
export struct Index {
  private message = '弹窗'
  @Builder customDialogComponent(dialogController: promptAction.DialogController) {
    Column({ space: 5 }) {
      Text(this.message)
        .fontSize(30)
      if (dialogController !== undefined) {
        Button('点击关闭弹窗：通过外部传递的DialogController')
          .onClick(() =&gt; {
            dialogController.close()
          })
      }
    }
    .height(200)
    .padding(5)
    .justifyContent(FlexAlign.SpaceBetween)
    .backgroundColor('#FFF0F0F0')
  }

  @Builder customDialogComponentWithId(dialogId: number, dialogController: promptAction.DialogController) {
    Column({ space: 5 }) {
      Text(this.message)
        .fontSize(30)
      if (dialogId !== undefined) {
        Button('点击关闭弹窗：通过DialogID')
          .onClick(() =&gt; {
            this.getUIContext().getPromptAction().closeCustomDialog(dialogId)
          })
      }
      if (dialogController !== undefined) {
        Button('点击关闭弹窗：通过外部传递的DialogController')
          .onClick(() =&gt; {
            dialogController.close()
          })
      }
    }
  }

  private baseDialogOptions: promptAction.BaseDialogOptions = {
    isModal: false,
    autoCancel: false
  }

  private dialogOptions: promptAction.DialogOptions = {
    isModal: false,
    autoCancel: false
  }

  build() {
    Column({ space: 5 }) {
      Button('openCustomDialogWithController弹窗')
        .onClick(() =&gt; {
          let dialogController: promptAction.CommonController = new promptAction.DialogController()
          let contentNode: ComponentContent&lt;Object&gt; =
            new ComponentContent(this.getUIContext(), wrapBuilder(buildText), new Params(this.message, dialogController))
          this.getUIContext().getPromptAction().openCustomDialogWithController(
            contentNode, dialogController, this.baseDialogOptions).catch((err: BusinessError) =&gt; {
            console.error('openCustomDialogWithController error: ' + err.code + ' ' + err.message)
          })
        })
      Button('presentCustomDialog+CustomBuilder弹窗')
        .onClick(() =&gt; {
          let dialogController: promptAction.CommonController = new promptAction.DialogController()
          this.getUIContext().getPromptAction().presentCustomDialog(() =&gt; {
            this.customDialogComponent(dialogController)
          }, dialogController, this.dialogOptions).catch((err: BusinessError) =&gt; {
            console.error('presentCustomDialog error: ' + err.code + ' ' + err.message)
          })
        })
      Button('presentCustomDialog+CustomBuilderWithId弹窗')
        .onClick(() =&gt; {
          let dialogController: promptAction.CommonController = new promptAction.DialogController()
          this.getUIContext().getPromptAction().presentCustomDialog((dialogId: number) =&gt; {
            this.customDialogComponentWithId(dialogId, dialogController)
          }, dialogController, this.dialogOptions).catch((err: BusinessError) =&gt; {
            console.error('presentCustomDialog error: ' + err.code + ' ' + err.message)
          })
        })
      Button('CustomDialogController弹窗')
        .onClick(() =&gt; {
          let customDialogController: CustomDialogController = new CustomDialogController({
            builder: CustomDialogExample(),
          })
          customDialogController.open()
        })
    }.width('100%')
  }
}</pre>
        <p><span><img originheight="666" originwidth="425"
                      src="https://communityfile-drcn.op.dbankcloud.cn/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20250709163043.84495126534618338494506467640875:50001231000000:2800:39CAC449421028BD26AD3B069165D64B288A490EF33D505172B02C3C6D1FC524.gif"></span>
        </p></div>
</div>
<div></div>
</body>
</html>